Table of Contents

Use the following to generate a table of contents... ```{toc} ```

Output:

Page Title

Set the title of the output document using the title inline/block tag:

```{title}
Markdown Example!
```

Output: (see the title of this HTML page)

If you're using a block tag, make sure you put the title on a NEW line (not on the same line that declares the tag).

Bookmarks

You can automatically link back to any piece of text by using the bm inline tag:

The tag can take in either 1 argument or 3 arguments, where forward-slashes (/) are used to delimit arguments. If required, use back-slash to escape the delimiter (e.g. \/).

Usage examples:

In certain cases, multiple bookmarks may match a certain piece of text. To resolve this, the bookmark with the longest piece of text captured by the capture group is the one that gets linked to. For example, if the bookmarks Samsung (Galaxy) and Samsung (Galaxy Smartphone) matched on the text Samsung Galaxy Smartphone Holder, the second bookmark would get chosen because capture group 1 returns a longer piece of text.

If the length of the captured text between the matches are equal, an error is thrown and you'll need to find a way to disambiguate. 2 options are available:

  1. You can explicitly prevent a piece of text from being matched to any bookmark by wrapping it in a bm-r inline tag (`{bm-ri} TEXT`). For example, coke zero should link to the example above but coke zero won't.
  2. You can use the bm-ambiguous inline tag (`{bm-ambiguous} ERROR_TEXT/REGEX/REGEX_FLAGS`) to generate an error telling the user that they need to disambiguate. For example, you may want to create a bookmark for the word base, but in 2 different contexts: base as in pH scale and base as in nitrogenous base. You can use the bm-ambiguous tag to catch any instances of base and throw an error notify the user that they need to provide a more specialized version (e.g. `{bm-ambiguous} Base is too ambiguous. Use either base_pH or base_nucleotide/\b(base)\b/i`), which you can target using normal bm tags (e.g. `{bm} base/\b(base)_nucleotide?\b/i` -- this will match base_nucleotide but only output base).

Image Annotations

You can include local images and annotate / scale / crop them using the img block tag:

```{img}
201903_Ribosome.svg
Diagram of ribosome translating messanger RNA
By DataBase Center for Life Science (DBCLS) - http://togotv.dbcls.jp/ja/togopic.2019.06.html, CC BY 4.0, https://commons.wikimedia.org/w/index.php?curid=77793595
scale 0.25 0.25
text 0.1 0.1 mRNA strand
arrow 0.1 0.1  0.1 0.55  0.2 0.55
highlight_poly 0.15 0.4  0.6 0.75  0.75 0.75  0.20 0.25
```

Output:

Diagram of ribosome translating messanger RNA

The first 3 lines must be as follows:

  1. file name (should sit in the same directory as input.md).
  2. alternative text for the image (e.g. description of the image).
  3. title text for the image (e.g. attribution).

Subsequent lines are commands that you can use to manipulate and annotate the image...

Notes

Generate notes by using the note block tag:

```{note}
This is a custom note.
```

Output:

NOTE: This is a custom note.

TODO: Add CSS styling for this.

CSV Table

Add a table using the CSV block tag:

```{csv}
!!{ "firstLineHeader": true }
Code,Country
AFG,Afghanistan
ALB,Albania
ALG,Algeria
ASA,American Samoa
AND,Andorra
ANG,Angola
AIA,Anguilla
ATG,Antigua and Barbuda
```

Block output:

CodeCountry
AFGAfghanistan
ALBAlbania
ALGAlgeria
ASAAmerican Samoa
ANDAndorra
ANGAngola
AIAAnguilla
ATGAntigua and Barbuda

Math Typesetting

You can typeset math expressions using different HTML type setting engines.

NOTE: Right now, the preferred method of typesetting is to use KaTeX because it's more lightweight. MathJax 3 may change this (we're using an inline version of MathJax 2).

MathJax

Add a MathJax TeX expression using mj inline/block tag:

```{mj}
\frac{a}{b}
```

Inline output: $\frac{a}{b}$

Block output:

$$\frac{a}{b} $$

KaTeX

Add a KaTeX TeX expression using kt inline/block tag:

```{kt}
\frac{a}{b}
```

Inline output: ab\frac{a}{b}

Block output:

ab\frac{a}{b}

Diagrams

GraphViz (dot)

Generate Graphviz dot diagrams by using dot block tag:

```{dot}
digraph {
  a -> b;
  b -> c;
  b -> d;
}
```

Output:

Graphviz Dot Diagram

PlantUML

Add a PlantUML diagram using the plantuml block tag:

```{plantuml}
@startuml
class Student {
  Name
}
Student "0..*" - "1..*" Course
(Student, Course) .. Enrollment

class Enrollment {
  drop()
  cancel()
}
@enduml
```

Block output:

PlantUML Diagram

Language Support

You can generate output by passing in custom code to run in various programming languages. The code is built and run in an isolated container, so it should be safe. The container is set up such that...

Your custom code must generate exactly 1 file in the /output directory . That file must end in either .txt, .csv, .svg, .png, .gif, .jpg, or .jpeg -- the extension defines how the file gets displayed in the final markup.

NOTE: This may be useful for generating custom graphs/diagrams, or for doing various computations.

Python

Add an image or text generated via Python (miniconda) using the conda block tag:

```{python}
f = open("/output/text.txt","w+")
f.write("hello world!")
f.close()
```

```{python}
dependencies:
  - python=3.7
  - matplotlib=3.1
----
import matplotlib.pyplot as plt
plt.plot([1, 2, 3, 4])
plt.ylabel('some numbers')
plt.savefig("/output/out.svg", format="svg")
```

The Miniconda environment YAML and Python source code are separated by ----.

Block output:

hello world!

Generated image

Java

Add an image or text generated via Java (maven) using the java block tag:

```{java}
import java.io.*;
import java.nio.charset.*;
import java.nio.file.*;
import java.util.*;

public class Main {
  public static void main(String[] args) {
    Files.write(Paths.get("/output/text.txt"), "hello world".getBytes(StandardCharsets.UTF_8), StandardOpenOption.CREATE);
  }
}
```

```{java}
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>unused</groupId>
  <artifactId>unused</artifactId>
  <version>unused</version>
  
  <properties>
    <maven.compiler.source>12</maven.compiler.source>
    <maven.compiler.target>12</maven.compiler.target>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.apache.xmlgraphics</groupId>
      <artifactId>batik-all</artifactId>
      <version>1.11</version>
    </dependency>
  </dependencies>
</project>
----
import java.awt.*;
import java.io.*;
import org.apache.batik.svggen.SVGGraphics2D;
import org.apache.batik.dom.GenericDOMImplementation;
import org.w3c.dom.Document;
import org.w3c.dom.DOMImplementation;

public class Main {

  public static void main(String[] args) throws IOException {
    DOMImplementation domImpl = GenericDOMImplementation.getDOMImplementation();

    String svgNS = "http://www.w3.org/2000/svg";
    Document document = domImpl.createDocument(svgNS, "svg", null);

    SVGGraphics2D svgGenerator = new SVGGraphics2D(document);
    svgGenerator.setPaint(Color.red);
    svgGenerator.fill(new Rectangle(10, 10, 100, 100));

    try (FileOutputStream fos = new FileOutputStream("/output/output.svg");
        Writer out = new OutputStreamWriter(fos, "UTF-8")) {
      svgGenerator.stream(out, true);
    }
  }
}
```

The Maven POM XML and Java source code are separated by ----.

Block output:

hello world

Generated image

NodeJS

Add an image or text generated via NodeJS (npm) using the node block tag:

```{node}
const fs = require('fs');
fs.writeFileSync("/output/output.txt", "Hey there!", { encoding: 'utf8' });
```

```{node}
{
  "scripts": {
    "start": "node code.js"
  },
  "dependencies": {
    "pureimage": "0.1.6"
  }
}
----
const fs = require('fs');
const PImage = require('pureimage');

var img = PImage.make(100,100);
var ctx = img.getContext('2d');
ctx.fillStyle = '#00ff00';
ctx.beginPath();
ctx.arc(50,50,40,0,Math.PI*2,true); // Outer circle
ctx.closePath();
ctx.fill();

PImage.encodePNGToStream(img, fs.createWriteStream('/output/out.png')).then(() => {
    console.log("wrote out the png file to out.png");
}).catch((e)=>{
    console.log("there was an error writing");
});
```

The NPM package JSON and Javascript source code are separated by ----.

Block output:

Hey there!

Generated image

Standard Markdown

Standard Markdown syntax guide (adapted from https://github.com/tchapi/markdown-cheatsheet).

Headers

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
NOTE: Outputs left out so as to not pollute the table of contents.

Text Formatting

Emphasized text:

text --> _text_ or *text*

Strong text:

text --> __text__ or **text**

Strong emphasized text:

text --> ___text___ or ***text***

Link:

text --> [text](http://www.google.com")

Block quote:

Blockquote

Nested blockquote

> Blockquote
>> Nested blockquote

Horizontal line:


- - - -

Image

Image:

![Messenger RNA structure](https://upload.wikimedia.org/wikipedia/commons/b/ba/MRNA_structure.svg)

Lists

Unordered list:

* Some item 
    * Some inner item
        * Some inner inner item
* Some other item

Ordered list:

  1. Some item
    1. Some inner item
      1. Some inner inner item
      2. Some inner inner item
  2. Some other item
1. Some item 
    1. Some inner item
        1. Some inner inner item
        1. Some inner inner item
1. Some other item

Table

No flavour of markdown tables are supported. You can use CSV tables instead.

Code

Code can either be inline in a paragraph or as a standalone block. Only standalone blocks can have syntax highlighting.

Inline code block example:

inlineCode(arg1, arg2) --> `inlineCode(arg1, arg2)`

Block code block example:

import java.io.*;
import java.nio.charset.*;
import java.nio.file.*;
import java.util.*;

public class Main {
  public static void main(String[] args) throws Throwable {
    Files.write(Paths.get("/output/text.txt"), "hello world".getBytes(StandardCharsets.UTF_8), StandardOpenOption.CREATE);
  }
}
```java
import java.io.*;
import java.nio.charset.*;
import java.nio.file.*;
import java.util.*;

public class Main {
  public static void main(String[] args) throws Throwable {
    Files.write(Paths.get("/output/text.txt"), "hello world".getBytes(StandardCharsets.UTF_8), StandardOpenOption.CREATE);
  }
}
```